<html>

<!-- ====================================================== -->
<head>
<title id="head_title">webimidi</title>
<style type="text/css">

/*-----------------------------------------------------------------*/
pre {
    font-weight: bold;
    overflow:    auto;
    border:      0;
    padding:     1em; 
    margin:      1em;
}

/*-----------------------------------------------------------------*/
h1,h2,h3,h4,h5 {
    padding:       0.5em;
    border:        0;
    background:    #C0C0FF;
}

</style>
<script type="text/javascript">
function body_onload() {
    var head_title = document.getElementById("head_title").innerHTML
    document.getElementById("body_title").innerHTML = head_title
}
</script>
</head>

<!-- ====================================================== -->
<body onload="body_onload()">

<!-- ====================================================== -->
<h1 id="body_title">title should have been filled in via JavaScript</h1>

<p><i>It's an HTTP server <b>AND</b> a herd of MIDI devices!</i></p>

<p>webimidi is a Python program which runs as a web server,
and creates virtual MIDI devices which can be accessed via
HTTP.  This allows you to create virtual MIDI controllers
as web applications, using nothing but HTML, CSS, and JavaScript.
</p>

<p>The real intention of this program is to be able to access
these virual MIDI controllers via a portable device such
as an iPhone, Nokia N800, Nintendo DS, or other HTTP 
capable device.</p>

<!-- ====================================================== -->
<h2>Caveats</h2>

<ul>
<li><p>The server currently only runs on Mac OS X 10.5 or later.</p></li>
<li><p>MIDI devices can only be written to, they cannot be read.</p></li>
<li><p>Currently only NoteOn, NoteOff, and ControlChange messages can be written.</p></li>
</ul>

<!-- ====================================================== -->
<h2>Installation and Usage</h2>

<ol>
<li><p>Download a webimidi archive from 
<a href="http://code.google.com/p/webimidi/">http://code.google.com/p/webimidi/</a>
and unpack using the appropriate unpacking tool.</p></li>

<li><p>'cd' into the webimidi directory created.</p></li>

<li><p>Invoke the webimidi server with the command:
<pre>
python webimidid.py 8088 sample
</pre>
The first parameter is the tcp/ip port which the HTTP server will be run at.
The second parameter is the name of a directory that contains the devices
to create, one subdirectory per device.  The devices created will have
the name of the subdirectory.
</p></li>

<li><p>The webimidi server should now be running with one device from the <tt>sample</tt>
directory, <b>simple-keys</b>.</p></li>

<li><p>Open a MIDI-enabled application, like 
<a href="http://www.ableton.com/">Ableton Live</a>
or
<a href="http://www.cockos.com/reaper/">Cockos Reaper</a>.</p></li>

<li><p>The MIDI device <tt>simple-keys</tt> will be available
which will generate MIDI note messages.  You will likely have to
futz around to get the MIDI device enabled, but you probably
already know how to do that, or can figure it ou.  Assign that MIDI device's output
to a software instrument in your application.</p></li>

<li><p>If you are accessing the server from a difference machine / device,
make sure you have the firewall off in System Preferences / Security.</p></li>

<li><p>Browse to the location
<a href="http://localhost:8088/">http://localhost:8088/</a> .
</p></li>

<li><p>Click on the 
<a href="http://localhost:8088/devices/simple-keys/">simple-keys</a> 
link.</p></li>

<li><p>Click the piano keys with your mouse, stylus, whatever. Have fun.</p></li>

<li><p>Kill the server by pressing Control-C at the command-line.</p></li>

</ol>

<!-- ====================================================== -->
<h2>Creating New Devices</h2>

<ol>
<li><p>Learn HTML.</p></li>  
<li><p>Learn CSS.</p></li>
<li><p>Learn JavaScript.</p></li>
<li><p>Learn <a href="http://jquery.com/">jQuery</a>.</p></li>
<li><p>Study the sample device simple-keys.</p></li>
<li><p>Create a new directory next to the <tt>simple-keys</tt> directory (the
directories will have the same parent directory).</p></li>
<li><p>Using your new HTML/CSS/JavaScript/jQuery skillz, create
your new device rooted in an index.html file.</p></li>
<li><p>The file <tt>midi.js</tt> can be reused as is,
or extended for nefarious purposes.</p></li>
</ol>

<p>Technically, having a subdirectory in the device directory
(second parameter to webimidid.py) is all that's needed to have
the MIDI device created.  In order to send messages to the
device, you'll need to issue HTTP POST requests to the URL
assigned to the device.  For more information on the API,
see the <b>API</b> section of the document.</p>

<p>In the device directory, you can create an index.html file
which will be accessible via URL
<tt>http://[hostname]:[port]/devices/[device-name]/</tt>.
That file can contain the HTML, CSS, and JavaScript to render
a user interface to interact with the MIDI device.  Other
files in the subdirectory are accessible via their existing
file names.  For instance, the file <tt>midi.js</tt> shipped
with the <tt>simple-keys</tt> device is available via the
URL 
<tt>http://[hostname]:[port]/devices/[device-name]/midi.js</tt>.
</p>

<!-- ====================================================== -->
<h2>About the MIDI Programming Interface</h2>
<p>Written in pure, mother-loving Python, using the
<a href="http://docs.python.org/lib/module-ctypes.html">ctypes</a>
built-in module to interface with the 
<a href="http://developer.apple.com/documentation/MusicAudio/Conceptual/CoreAudioOverview/CoreAudioFrameworks/chapter_950_section_6.html">Mac OS X CoreMIDI Framework</a>.
The inspiration to interface with ctypes was from 
looking at the source code for Giles Bowkett's
<a href="http://github.com/gilesbowkett/archaeopteryx/wikis/home">Archaeopteryx</a>.
</p>

<p>Further information on how to call into the CoreMIDI framework was
discovered by perusing the source for the
<a href="http://dsmidiwifi.tobw.net/">DSMI project</a>.</p>

<!-- ====================================================== -->
<h2>API</h2>

<p>Under review.  Pretty easy to figure out by looking at
the source code.</p>

<!-- ====================================================== -->
<h2>Questions, Discussion</h2>

<p><a href="http://groups.google.com/group/webimidi">webimidi Google Group</a></p>

<!-- ====================================================== -->
<h2>Source</h2>

<p><a href="http://code.google.com/p/webimidi/">webimidi @ Google code</a></p>

<!-- ====================================================== -->
<h2>Author</h2>

<p><a href="http://muellerware.org/">Patrick Mueller</a></p>

<!-- ====================================================== -->
<h2>History</h2>

<p><b>2008/10/18 - version 0.1</b></p>
<ul>
<li>Initial version</li>
</ul>

<!-- ====================================================== -->
<h2>License</h2>

<p><b><tt>webimidi/lib/simplejson</tt></b><br/>
See 
<a href="http://code.google.com/p/simplejson/">http://code.google.com/p/simplejson/</a>.
Currently licensed using the 
<a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.
</p>

<p><b><tt>webimidi/sample/simple-keys/jquery*.js</tt></b><br/>
See 
<a href="http://jquery.com/">http://jquery.com/</a>.
Currently licensed using the 
<a href="http://jquery.com/dev/svn/trunk/jquery/MIT-LICENSE.txt">MIT license</a>
and/or/something the
<a href="http://jquery.com/dev/svn/trunk/jquery/GPL-LICENSE.txt">GPL license</a>.
</p>

<p><b><tt>webimidi/sample/json2.js</tt></b><br/>
See
<a href="http://www.JSON.org/json2.js">http://www.JSON.org/json2.js</a>.
Currently in the public domain.
</p>

<p><b><tt>Everything else</tt></b><br/>
Currently licensed using the 
<a href="http://www.opensource.org/licenses/mit-license.php">MIT license</a>.
</p>

</body>

</html>